/**
 *	@author: Kathleen Go
 *	date created: February 11, 2006
 *	version: 1.0
 * modified: 
 */

package text.learning;

import java.util.Vector;
import java.util.Hashtable;

import text.obj.TExtChunk;

public interface ChunkAligner{
	
	/**	Finds the alignment of chunks between the chunks ({@link TExtChunk}) of a Source sentence
	 * 		and the chunks ({@link TExtChunk}) of a Target sentence.
	 * 
	 *	Returns the {@link Hashtable} of aligned chunks.
	 *
	 *	@param vChunkSource a {@link Vector} representing the Source chunks (TExtChunk) to be aligned
	 *	@param vChunkTarget a {@link Vector} representing the Target chunks (TExtChunk) to be aligned
	 *	@param alignedWords a {@link Hashtable} containing the alignment of the chunks' tokens
	 *	@return the {@link Hashtable} containing the aligned chunks
	 *			a chunk from the source sentence is stored as a KEY
	 *			a KEY entry is a {@link TExtChunk}
	 *			corresponding VALUEs are the matched chunks in the target sentence
	 *			a VALUE entry is a {@link Vector} consisting of at least 1 {@link TExtChunk}
	 */
	public Hashtable alignChunks(Vector vChunkSource, Vector vChunkTarget, Hashtable alignedWords);	

	/**	This returns the index mapping of the aligned Source and Target chunks.
	 *	
	 *	Returns a {@String} representing index mapping of the alignment of the Source and
	 *		Target chunks handled by a TExtChunkAligner object.
	 *
	 *	@return the {@String} representing the index mapping of the alignment of the Source
	 *		and Target chunks handled by a TExtChunkAligner object.
	 */
	public String getStringMapping();

	/**	Returns the {@Vector} of aligned Source chunks and the Vector of aligned
	 *		Target chunks handled by a TExtChunkAligner object.
	 *
	 *	@return the {@Vector} of aligned Source chunks and the Vector of aligned
	 *		Target chunks handled by a TExtChunkAligner object
	 *			Index 0 is a Vector that contains the Vector of aligned Source chunks.
	 *			Index 1 is a Vector that contains the Vector of aligned Target chunks.
	 */
	public Vector getCurrentAlignedChunks();

	/**	Given the Vector of Source chunks (vSource) and Vector of Target chunks (vTarget),
	 *		this function attemps to align as many as possible by checking the Chunks DB
	 *		for existing alignments. This function handles exact matches.
	 *	Returns the {@link Hashtable} of aligned chunks.
	 *
	 *	@param vSource a {@link Vector} representing the Source chunks (TExtChunk) to be aligned
	 *	@param vTarget a {@link Vector} representing the Target chunks (TExtChunk) to be aligned
	 *	@return the {@link Vector} containing the unaligned chunks
	 *		Index 0 is the Vector that contains the remaining unaligned Source chunks
	 *		Index 1 is the Vector that contains the remaining unaligned Target chunks
	 */
	public Vector useExistingChunksDB(Vector vSource, Vector vTarget);

	/**	Given a Source chunk ({@TExtChunk} chunkSource) and a {@Vector} of Target chunks
	 *		(vTarget), this function compares chunkSource with each element of vTarget such
	 *		that for each Source-Target pair, their alignment will be scored by counting
	 *		the number of aligned tokens they have.  For each pair, there are two scores
	 *		such that one score measures the number of aligned important words while the
	 *		other measures the score of the all alignments.  As each Source-Target chunk
	 *		pair is compared, a Source-to-Target alignment array is constructed to show
	 *		which Source token is aligned to which Target token by recording their indices.
	 *		A Target-to-Source alignment array is also constructed to show which Target
	 *		token is aligned to which Source token by recording their indices.
	 *
	 *	@param chunkSource a {@link TExtChunk} representing the Source chunk (TExtChunk) to be aligned
	 *	@param vTarget a {@link Vector} representing the Target chunks (TExtChunk) to be aligned
	 *	@param cCallerFunc a character indicating what is needed by the calling function.  A value of 'a' means that the caller needs the scores of all pairs.  A value 'b' means that
	 *		the caller needs the Target chunk that is closely aligned to the given Source chunk.
	 *	@param bFromSplitter a boolean indicating whether the caller needs the Source-to-Target and Target-to-Source alignment matrices.
	 *	@return the {@link Vector} containing comparison results depending on the value of cCallerFunc
	 *		If cCallerFunc == 'a'
	 *				Index 0 is the Target chunk that is the most closely aligned to chunkSource
	 *				Index 1 is the index of the object in Index 0 among the given Target chunks
	 *		If cCallerFunc == 'b'
	 *				Index 0 is the array of scores that measures all alignments
	 *				Index 1 is the array of scores that measures the alignments of important words
	 *			If bFromSplitter == true
	 *				Index 2 is the Source-to-Target alignment matrix of the given Source chunk and Target chunks
	 *				Index 3 is the Target-to-Source alignment matrix of the given Source chunk and Target chunks
	 */
	public Vector alignFromAlignedWords(TExtChunk chunkSource, Vector vTarget, char cCallerFunc, boolean bFromSplitter);
}